Summary

This PR fixes issue #1443 where passing invalid tool types (e.g., raw functions instead of FunctionTool objects) in the tools list would pass initialization but fail at runtime.

Problem

Currently, when users mistakenly pass raw functions or other invalid types in the tools parameter, the error only appears during runtime:

agent = Agent(
    name="Test",
    tools=[some_function]  # Raw function, not FunctionTool
)

# Agent creation succeeds ✅

result = await Runner.run(agent, "test")
# ❌ Runtime error: AttributeError: 'function' object has no attribute 'name'
#    (in src/agents/run.py line 584)

This is confusing because:

1. The error happens far from where the mistake was made
2. The error message doesn't clearly explain what went wrong
3. Users might not understand they need to use @function_tool decorator

Why AttributeError Occurs at Runtime

The root cause is in src/agents/run.py:584:

current_span.span_data.tools = [t.name for t in all_tools]

This code assumes all items in all_tools have a .name attribute. However:

• Raw Python functions (type function) do NOT have a .name attribute (they only have __name__)
• Valid Tool objects (FunctionTool, FileSearchTool, etc.) all have a .name attribute

When a raw function reaches this line, Python raises AttributeError: 'function' object has no attribute 'name'.

The existing validation in Agent.__post_init__ only checks if tools is a list, not the type of each element:

if not isinstance(self.tools, list):
    raise TypeError("Agent tools must be a list, got ...")
# ❌ Does not validate individual tool types

Solution

Add validation in Agent.__post_init__ to check each tool in the list:

agent = Agent(
    name="Test",
    tools=[some_function]
)
# ❌ Immediate error at initialization:
# UserError: tools[0] must be a valid Tool object (FunctionTool, FileSearchTool, ...),
# got function. Did you forget to use @function_tool decorator or pass the function
# itself instead of a tool?

This provides better developer experience by:

• Early detection: Errors caught at initialization, not runtime
• Clear error messages: Explicitly states what went wrong
• Helpful suggestions: Mentions @function_tool decorator when raw functions detected

Changes

src/agents/agent.py:

• Added UserError import at module level
• Added validation loop in __post_init__ to check each tool type using get_args(Tool)
• Uses dynamic type extraction to automatically include all Tool types (FunctionTool, FileSearchTool, WebSearchTool, ComputerTool, HostedMCPTool, LocalShellTool, ImageGenerationTool, CodeInterpreterTool, and Handoff)

tests/test_agent_config.py:

• Added test_tools_content_validation_issue_1443 with 3 test cases:
  • Case 1: Raw function in tools list
  • Case 2: String in tools list
  • Case 3: Mixed valid and invalid tools (verifies correct index is reported)

Testing

All tests pass:

pytest tests/test_agent_config.py::TestAgentValidation -v
# 6 passed

Note on PR #1927

This PR builds on the learnings from PR #1927. While #1927 attempted to change TypeError to UserError for existing validations, this PR adds new validation that was previously missing, preventing runtime AttributeError by catching invalid tool types early.

Fixes #1443